Skip to content

plugins: Box layout container for components panels (catalog 4) - #37420

Merged
nwparker merged 1 commit into
mainfrom
nwparker/plugin-components-box
Nov 2, 2026
Merged

nwparker merged 1 commit into
mainfrom
nwparker/plugin-components-box

Conversation

@nwparker

@nwparker nwparker commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​280 $\color{#cf222e}{\Huge{\mathbf{−}}}$​1 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​279
Prod 23 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​386 $\color{#cf222e}{\Huge{\mathbf{−}}}$​45 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​341

ELI5

Plugin panels built from Orca's components can now use Box, a general container for layout. Authors get rows, columns, grids, spacing, sizes, borders and theme backgrounds without raw HTML or CSS, so the panel still looks like Orca in light and dark.

What Changed

  • New Box component in the components catalog. ui.catalog goes from 3 to 4, and Box is available from Orca 1.4.248.
    • Layout: direction, columns, align, justify, wrap, grow, shrink, scroll.
    • Spacing: gap, padding, paddingX, paddingY, margin, all on the existing gap scale.
    • Sizes: width, height, min*, max*, in pixels (0–4096) or whole percents.
    • Look: border (true or a tone), radius, background (muted, card, or a tone's tint).
  • Props are checked strictly, like every other component. A hex colour, '50px', '120%', style or className is dropped with a warning. Typings reject these too.
  • The renderer turns props into fixed theme classes through data attributes. Only checked pixel and percent sizes go into inline style.
  • orca/testing: find/findAll read Box as a group, and summary() adds a line for a Box tinted or bordered in danger or warning.
  • Updated the typings, plugin-declarative-ui.md, the skill references and the bundled guides. The components gallery gets a Layout tab and now requires Orca 1.4.248.

Why

Authors needed a layout that Stack/Row/Grid/Card can't express, such as a fixed-width side box or a tinted, scrolling region. Until now their only option was to leave components panels. A token-only container keeps plugins themable. We considered allowing arbitrary style and rejected it because it breaks theming.

Linked Issue

N/A (maintainer)

Visual Proof

Taken with orca plugin shot from a background dev build, using a demo panel built from Box only.

Light:

Box demo light

Dark:

Box demo dark

Testing

  • I manually tested these changes locally (macOS, plugin shot light and dark, plugin check on the gallery, and a tsc run of a demo plugin against the generated typings, which rejects background="#fff")
  • Automated tests added/updated: prop validation, rendering and nesting, and testing-kit queries and summary. The gallery test and the catalog-version assertion are updated.

Also ran pnpm lint, the changed-code quality gate, ast-grep, the anti-slop lint, the localization check, and the freshness tests for the runtime, typings and skill references.

Risk

The change only adds to the catalog. Older Orca versions draw an unknown Box as a placeholder. The gallery example's engine floor goes up to 1.4.248. A plain revert undoes everything.

Level: Low

AI Disclosure

Review

Agent skill upstream boundary

  • Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Renderer-only and the same on all platforms. SSH is not affected, because panels render on the client.

Checklist

  • This PR is small and focused
  • I explained what changed and why
  • I stated the risk
  • Screenshots attached
  • Self-reviewed
  • Cross-platform/SSH considered
  • pnpm lint and the targeted tests pass (CI covers the rest)

- Box (ui.catalog 4, since 1.4.248): direction, gap/padding/paddingX/
  paddingY/margin on the gap scale, align, justify, wrap, grow, shrink,
  width/height/min/max (px up to 4096 or whole percents), columns,
  scroll, border (true or a tone), radius, background (theme surfaces or
  tone tints). Strict props: hex colours, CSS lengths and unknown props
  are dropped with a warning like other components.
- Renderer maps props to theme tokens through data attributes; sizes
  reach inline style only as validated px or percents.
- Typings, docs, skill references, gallery Layout tab; orca/testing
  finds Boxes and summarizes danger or warning Boxes.
@nwparker
nwparker merged commit 36f17a0 into main Nov 2, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant